5.1 File Editing and Todo Edit Mode

There are four file-level editing commands:

F a

Add a new todo file (todo-add-file). This command prompts for a name and creates the file in todo-directory, adding the ‘.todo’ extension (so you should not include the extension in the name you enter). The command also prompts for the file’s first category and, if option todo-add-item-if-new-category is enabled (the default), for that category’s first item.

F r

Rename the current todo file (todo-rename-file). If called with a prefix argument, prompt for a todo file and rename it. If the todo file has an archive (see Todo Archive Mode) or there are corresponding filtered items files (see Todo Filtered Items Mode), this command renames these accordingly. If there are live buffers visiting any of these files, the command also renames them accordingly.

F k

Delete the current todo file (todo-delete-file).⁴ If the todo file has an archive (see Todo Archive Mode), prompt for whether to delete that as well. This command also kills the buffers visiting the deleted files.

F e

This command (todo-edit-file) changes the buffer’s major mode to Todo Edit mode. In this mode the entire file is visible, the buffer is writable and you can use the self-insertion keys and standard Emacs editing commands to make changes. To return to Todo mode, type C-x C-q (todo-edit-quit).

The command F e is not intended for normal editing of items and categories, as it circumvents the restrictions that Todo imposes to protect against file format corruption (i.e., all categories, not just the current one, and all internal formatting are exposed and editable). It is provided primarily as a convenience for two types of use cases that are likely to arise infrequently. One is to be able to use standard Emacs commands like query-replace to replace a piece of text that occurs in different categories throughout the file. The other use case is to recover from a mistake, such as accidentally deleting an item, since this cannot be undone in Todo mode.

Using C-x C-q to quit Todo Edit mode provides a measure of safety, since it runs a file format check, signaling an error if the format has become invalid. However, this check cannot tell if the number of items or categories changed, which could result in the file containing inconsistent information (see the cautionary note in Reordering Categories, for more details). Invoking F e displays a warning to this effect.